Scripting
开始
文档
更新日志
隐私
开始
文档
更新日志
隐私
简体中文

读取分类数据（HealthCategorySample）

Scripting 应用支持通过全局函数 Health.queryCategorySamples() 访问 HealthKit 中的分类健康数据。分类样本表示某一健康事件或状态的记录，通常包括起止时间和一个离散的状态值，例如：睡眠分析、冥想记录、经期流量、排卵测试结果等。

本文将介绍如何查询、解析并使用这些分类数据。

什么是 Category Sample？

Category Sample（分类样本） 包含以下信息：

  • type：样本的分类类型（如 "sleepAnalysis"、"mindfulSession"）
  • startDate / endDate：事件发生的起止时间
  • value：表示事件状态的整数值，需使用对应的枚举进行解释
  • metadata：可选的附加信息

常见示例：

  • "sleepAnalysis" 对应的值可以是 asleepCore、awake、inBed
  • "menstrualFlow" 对应的值可以是 mild、moderate、severe

API 用法

1Health.queryCategorySamples(
2  categoryType: HealthCategoryType,
3  options?: {
4    startDate?: Date
5    endDate?: Date
6    limit?: number
7    strictStartDate?: boolean
8    strictEndDate?: boolean
9    sortDescriptors?: Array<{
10      key: "startDate" | "endDate" | "value"
11      order?: "forward" | "reverse"
12    }>
13  }
14): Promise<HealthCategorySample[]>

参数说明

参数名 描述
categoryType 要查询的分类数据类型（如 "sleepAnalysis"）
startDate / endDate 筛选结果的时间范围
limit 返回的最大样本数量
strictStartDate / strictEndDate 是否严格匹配起止时间
sortDescriptors 可选排序规则，例如按 startDate、endDate 或 value 排序

示例：读取睡眠分析数据

1const results = await Health.queryCategorySamples("sleepAnalysis", {
2  startDate: new Date("2025-07-01T00:00:00"),
3  endDate: new Date("2025-07-05T00:00:00"),
4  sortDescriptors: [{ key: "startDate", order: "forward" }]
5})
6
7for (const sample of results) {
8  console.log("开始时间：", sample.startDate)
9  console.log("结束时间：", sample.endDate)
10  console.log("睡眠状态值：", sample.value) // 需要使用枚举解释该值
11}

你可以使用对应的枚举来解释 value 值：

1switch (sample.value) {
2  case HealthCategoryValueSleepAnalysis.awake:
3    console.log("清醒")
4    break
5  case HealthCategoryValueSleepAnalysis.asleepCore:
6    console.log("核心睡眠")
7    break
8  case HealthCategoryValueSleepAnalysis.asleepDeep:
9    console.log("深度睡眠")
10    break
11  case HealthCategoryValueSleepAnalysis.inBed:
12    console.log("在床上")
13    break
14  // 可根据需要继续扩展其他状态
15}

示例：读取冥想记录

1const sessions = await Health.queryCategorySamples("mindfulSession", {
2  startDate: new Date(Date.now() - 7 * 86400 * 1000) // 最近 7 天
3})
4
5console.log(`共找到 ${sessions.length} 条冥想记录`)

注意事项

  • 所有返回结果都是 HealthCategorySample 实例
  • .value 是一个整数，需要使用对应类型的枚举进行解释
  • .metadata 字段为可选，可提供附加信息（如来源、标签等）
  • 分类数据适用于建模事件型健康记录，例如睡眠、冥想、生理周期、症状等

小结

要读取分类样本数据：

  1. 调用 Health.queryCategorySamples(categoryType, options)
  2. 设置时间范围、数量限制、排序方式等参数
  3. 使用 .value 配合相应枚举来解释数据含义

该 API 提供了对基于事件的健康数据的结构化访问方式，适用于日志展示、趋势分析等场景。

大纲